home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_xemacs.idb / usr / freeware / lib / xemacs-20.4 / info / internals.info-6.z / internals.info-6
Encoding:
GNU Info File  |  1998-05-21  |  49.9 KB  |  1,228 lines
  1. This is Info file ../../info/internals.info, produced by Makeinfo
  2. version 1.68 from the input file internals.texi.
  3.  
  4.    Copyright (C) 1992 - 1996 Ben Wing.  Copyright (C) 1996, 1997 Sun
  5. Microsystems.  Copyright (C) 1994, 1995 Free Software Foundation.
  6. Copyright (C) 1994, 1995 Board of Trustees, University of Illinois.
  7.  
  8.    Permission is granted to make and distribute verbatim copies of this
  9. manual provided the copyright notice and this permission notice are
  10. preserved on all copies.
  11.  
  12.    Permission is granted to copy and distribute modified versions of
  13. this manual under the conditions for verbatim copying, provided that the
  14. entire resulting derived work is distributed under the terms of a
  15. permission notice identical to this one.
  16.  
  17.    Permission is granted to copy and distribute translations of this
  18. manual into another language, under the above conditions for modified
  19. versions, except that this permission notice may be stated in a
  20. translation approved by the Foundation.
  21.  
  22.    Permission is granted to copy and distribute modified versions of
  23. this manual under the conditions for verbatim copying, provided also
  24. that the section entitled "GNU General Public License" is included
  25. exactly as in the original, and provided that the entire resulting
  26. derived work is distributed under the terms of a permission notice
  27. identical to this one.
  28.  
  29.    Permission is granted to copy and distribute translations of this
  30. manual into another language, under the above conditions for modified
  31. versions, except that the section entitled "GNU General Public License"
  32. may be included in a translation approved by the Free Software
  33. Foundation instead of in the original English.
  34.  
  35. 
  36. File: internals.info,  Node: Markers and Extents,  Next: Bufbytes and Emchars,  Prev: Buffer Lists,  Up: Buffers and Textual Representation
  37.  
  38. Markers and Extents
  39. ===================
  40.  
  41.    Among the things associated with a buffer are things that are
  42. logically attached to certain buffer positions.  This can be used to
  43. keep track of a buffer position when text is inserted and deleted, so
  44. that it remains at the same spot relative to the text around it; to
  45. assign properties to particular sections of text; etc.  There are two
  46. such objects that are useful in this regard: they are "markers" and
  47. "extents".
  48.  
  49.    A "marker" is simply a flag placed at a particular buffer position,
  50. which is moved around as text is inserted and deleted.  Markers are
  51. used for all sorts of purposes, such as the `mark' that is the other
  52. end of textual regions to be cut, copied, etc.
  53.  
  54.    An "extent" is similar to two markers plus some associated
  55. properties, and is used to keep track of regions in a buffer as text is
  56. inserted and deleted, and to add properties (e.g. fonts) to particular
  57. regions of text.  The external interface of extents is explained
  58. elsewhere.
  59.  
  60.    The important thing here is that markers and extents simply contain
  61. buffer positions in them as integers, and every time text is inserted or
  62. deleted, these positions must be updated.  In order to minimize the
  63. amount of shuffling that needs to be done, the positions in markers and
  64. extents (there's one per marker, two per extent) and stored in Meminds.
  65. This means that they only need to be moved when the text is physically
  66. moved in memory; since the gap structure tries to minimize this, it also
  67. minimizes the number of marker and extent indices that need to be
  68. adjusted.  Look in `insdel.c' for the details of how this works.
  69.  
  70.    One other important distinction is that markers are "temporary"
  71. while extents are "permanent".  This means that markers disappear as
  72. soon as there are no more pointers to them, and correspondingly, there
  73. is no way to determine what markers are in a buffer if you are just
  74. given the buffer.  Extents remain in a buffer until they are detached
  75. (which could happen as a result of text being deleted) or the buffer is
  76. deleted, and primitives do exist to enumerate the extents in a buffer.
  77.  
  78. 
  79. File: internals.info,  Node: Bufbytes and Emchars,  Next: The Buffer Object,  Prev: Markers and Extents,  Up: Buffers and Textual Representation
  80.  
  81. Bufbytes and Emchars
  82. ====================
  83.  
  84.    Not yet documented.
  85.  
  86. 
  87. File: internals.info,  Node: The Buffer Object,  Prev: Bufbytes and Emchars,  Up: Buffers and Textual Representation
  88.  
  89. The Buffer Object
  90. =================
  91.  
  92.    Buffers contain fields not directly accessible by the Lisp
  93. programmer.  We describe them here, naming them by the names used in
  94. the C code.  Many are accessible indirectly in Lisp programs via Lisp
  95. primitives.
  96.  
  97. `name'
  98.      The buffer name is a string that names the buffer.  It is
  99.      guaranteed to be unique.  *Note Buffer Names: (lispref)Buffer
  100.      Names.
  101.  
  102. `save_modified'
  103.      This field contains the time when the buffer was last saved, as an
  104.      integer.  *Note Buffer Modification: (lispref)Buffer Modification.
  105.  
  106. `modtime'
  107.      This field contains the modification time of the visited file.  It
  108.      is set when the file is written or read.  Every time the buffer is
  109.      written to the file, this field is compared to the modification
  110.      time of the file.  *Note Buffer Modification: (lispref)Buffer
  111.      Modification.
  112.  
  113. `auto_save_modified'
  114.      This field contains the time when the buffer was last auto-saved.
  115.  
  116. `last_window_start'
  117.      This field contains the `window-start' position in the buffer as of
  118.      the last time the buffer was displayed in a window.
  119.  
  120. `undo_list'
  121.      This field points to the buffer's undo list.  *Note Undo:
  122.      (lispref)Undo.
  123.  
  124. `syntax_table_v'
  125.      This field contains the syntax table for the buffer.  *Note Syntax
  126.      Tables: (lispref)Syntax Tables.
  127.  
  128. `downcase_table'
  129.      This field contains the conversion table for converting text to
  130.      lower case.  *Note Case Tables: (lispref)Case Tables.
  131.  
  132. `upcase_table'
  133.      This field contains the conversion table for converting text to
  134.      upper case.  *Note Case Tables: (lispref)Case Tables.
  135.  
  136. `case_canon_table'
  137.      This field contains the conversion table for canonicalizing text
  138.      for case-folding search.  *Note Case Tables: (lispref)Case Tables.
  139.  
  140. `case_eqv_table'
  141.      This field contains the equivalence table for case-folding search.
  142.      *Note Case Tables: (lispref)Case Tables.
  143.  
  144. `display_table'
  145.      This field contains the buffer's display table, or `nil' if it
  146.      doesn't have one.  *Note Display Tables: (lispref)Display Tables.
  147.  
  148. `markers'
  149.      This field contains the chain of all markers that currently point
  150.      into the buffer.  Deletion of text in the buffer, and motion of
  151.      the buffer's gap, must check each of these markers and perhaps
  152.      update it.  *Note Markers: (lispref)Markers.
  153.  
  154. `backed_up'
  155.      This field is a flag that tells whether a backup file has been
  156.      made for the visited file of this buffer.
  157.  
  158. `mark'
  159.      This field contains the mark for the buffer.  The mark is a marker,
  160.      hence it is also included on the list `markers'.  *Note The Mark:
  161.      (lispref)The Mark.
  162.  
  163. `mark_active'
  164.      This field is non-`nil' if the buffer's mark is active.
  165.  
  166. `local_var_alist'
  167.      This field contains the association list describing the variables
  168.      local in this buffer, and their values, with the exception of
  169.      local variables that have special slots in the buffer object.
  170.      (Those slots are omitted from this table.)  *Note Buffer-Local
  171.      Variables: (lispref)Buffer-Local Variables.
  172.  
  173. `modeline_format'
  174.      This field contains a Lisp object which controls how to display
  175.      the mode line for this buffer.  *Note Modeline Format:
  176.      (lispref)Modeline Format.
  177.  
  178. `base_buffer'
  179.      This field holds the buffer's base buffer (if it is an indirect
  180.      buffer), or `nil'.
  181.  
  182. 
  183. File: internals.info,  Node: MULE Character Sets and Encodings,  Next: The Lisp Reader and Compiler,  Prev: Buffers and Textual Representation,  Up: Top
  184.  
  185. MULE Character Sets and Encodings
  186. *********************************
  187.  
  188.    Recall that there are two primary ways that text is represented in
  189. XEmacs.  The "buffer" representation sees the text as a series of bytes
  190. (Bufbytes), with a variable number of bytes used per character.  The
  191. "character" representation sees the text as a series of integers
  192. (Emchars), one per character.  The character representation is a cleaner
  193. representation from a theoretical standpoint, and is thus used in many
  194. cases when lots of manipulations on a string need to be done.  However,
  195. the buffer representation is the standard representation used in both
  196. Lisp strings and buffers, and because of this, it is the "default"
  197. representation that text comes in.  The reason for using this
  198. representation is that it's compact and is compatible with ASCII.
  199.  
  200. * Menu:
  201.  
  202. * Character Sets::
  203. * Encodings::
  204. * Internal Mule Encodings::
  205. * CCL::
  206.  
  207. 
  208. File: internals.info,  Node: Character Sets,  Next: Encodings,  Up: MULE Character Sets and Encodings
  209.  
  210. Character Sets
  211. ==============
  212.  
  213.    A character set (or "charset") is an ordered set of characters.  A
  214. particular character in a charset is indexed using one or more
  215. "position codes", which are non-negative integers.  The number of
  216. position codes needed to identify a particular character in a charset is
  217. called the "dimension" of the charset.  In XEmacs/Mule, all charsets
  218. have dimension 1 or 2, and the size of all charsets (except for a few
  219. special cases) is either 94, 96, 94 by 94, or 96 by 96.  The range of
  220. position codes used to index characters from any of these types of
  221. character sets is as follows:
  222.  
  223.      Charset type            Position code 1         Position code 2
  224.      ------------------------------------------------------------
  225.      94                      33 - 126                N/A
  226.      96                      32 - 127                N/A
  227.      94x94                   33 - 126                33 - 126
  228.      96x96                   32 - 127                32 - 127
  229.  
  230.    Note that in the above cases position codes do not start at an
  231. expected value such as 0 or 1.  The reason for this will become clear
  232. later.
  233.  
  234.    For example, Latin-1 is a 96-character charset, and JISX0208 (the
  235. Japanese national character set) is a 94x94-character charset.
  236.  
  237.    [Note that, although the ranges above define the *valid* position
  238. codes for a charset, some of the slots in a particular charset may in
  239. fact be empty.  This is the case for JISX0208, for example, where (e.g.)
  240. all the slots whose first position code is in the range 118 - 127 are
  241. empty.]
  242.  
  243.    There are three charsets that do not follow the above rules.  All of
  244. them have one dimension, and have ranges of position codes as follows:
  245.  
  246.      Charset name            Position code 1
  247.      ------------------------------------
  248.      ASCII                   0 - 127
  249.      Control-1               0 - 31
  250.      Composite               0 - some large number
  251.  
  252.    (The upper bound of the position code for composite characters has
  253. not yet been determined, but it will probably be at least 16,383).
  254.  
  255.    ASCII is the union of two subsidiary character sets: Printing-ASCII
  256. (the printing ASCII character set, consisting of position codes 33 -
  257. 126, like for a standard 94-character charset) and Control-ASCII (the
  258. non-printing characters that would appear in a binary file with codes 0
  259. - 32 and 127).
  260.  
  261.    Control-1 contains the non-printing characters that would appear in a
  262. binary file with codes 128 - 159.
  263.  
  264.    Composite contains characters that are generated by overstriking one
  265. or more characters from other charsets.
  266.  
  267.    Note that some characters in ASCII, and all characters in Control-1,
  268. are "control" (non-printing) characters.  These have no printed
  269. representation but instead control some other function of the printing
  270. (e.g. TAB or 8 moves the current character position to the next tab
  271. stop).  All other characters in all charsets are "graphic" (printing)
  272. characters.
  273.  
  274.    When a binary file is read in, the bytes in the file are assigned to
  275. character sets as follows:
  276.  
  277.      Bytes           Character set           Range
  278.      --------------------------------------------------
  279.      0 - 127         ASCII                   0 - 127
  280.      128 - 159       Control-1               0 - 31
  281.      160 - 255       Latin-1                 32 - 127
  282.  
  283.    This is a bit ad-hoc but gets the job done.
  284.  
  285. 
  286. File: internals.info,  Node: Encodings,  Next: Internal Mule Encodings,  Prev: Character Sets,  Up: MULE Character Sets and Encodings
  287.  
  288. Encodings
  289. =========
  290.  
  291.    An "encoding" is a way of numerically representing characters from
  292. one or more character sets.  If an encoding only encompasses one
  293. character set, then the position codes for the characters in that
  294. character set could be used directly.  This is not possible, however, if
  295. more than one character set is to be used in the encoding.
  296.  
  297.    For example, the conversion detailed above between bytes in a binary
  298. file and characters is effectively an encoding that encompasses the
  299. three character sets ASCII, Control-1, and Latin-1 in a stream of 8-bit
  300. bytes.
  301.  
  302.    Thus, an encoding can be viewed as a way of encoding characters from
  303. a specified group of character sets using a stream of bytes, each of
  304. which contains a fixed number of bits (but not necessarily 8, as in the
  305. common usage of "byte").
  306.  
  307.    Here are descriptions of a couple of common encodings:
  308.  
  309. * Menu:
  310.  
  311. * Japanese EUC (Extended Unix Code)::
  312. * JIS7::
  313.  
  314. 
  315. File: internals.info,  Node: Japanese EUC (Extended Unix Code),  Next: JIS7,  Up: Encodings
  316.  
  317. Japanese EUC (Extended Unix Code)
  318. ---------------------------------
  319.  
  320.    This encompasses the character sets Printing-ASCII,
  321. Japanese-JISSX0201, and Japanese-JISX0208-Kana (half-width katakana,
  322. the right half of JISX0201).  It uses 8-bit bytes.
  323.  
  324.    Note that Printing-ASCII and Japanese-JISX0201-Kana are 94-character
  325. charsets, while Japanese-JISX0208 is a 94x94-character charset.
  326.  
  327.    The encoding is as follows:
  328.  
  329.      Character set            Representation (PC=position-code)
  330.      -------------            --------------
  331.      Printing-ASCII           PC1
  332.      Japanese-JISX0201-Kana   0x8E       | PC1 + 0x80
  333.      Japanese-JISX0208        PC1 + 0x80 | PC2 + 0x80
  334.      Japanese-JISX0212        PC1 + 0x80 | PC2 + 0x80
  335.  
  336. 
  337. File: internals.info,  Node: JIS7,  Prev: Japanese EUC (Extended Unix Code),  Up: Encodings
  338.  
  339. JIS7
  340. ----
  341.  
  342.    This encompasses the character sets Printing-ASCII,
  343. Japanese-JISX0201-Roman (the left half of JISX0201; this character set
  344. is very similar to Printing-ASCII and is a 94-character charset),
  345. Japanese-JISX0208, and Japanese-JISX0201-Kana.  It uses 7-bit bytes.
  346.  
  347.    Unlike Japanese EUC, this is a "modal" encoding, which means that
  348. there are multiple states that the encoding can be in, which affect how
  349. the bytes are to be interpreted.  Special sequences of bytes (called
  350. "escape sequences") are used to change states.
  351.  
  352.    The encoding is as follows:
  353.  
  354.      Character set              Representation (PC=position-code)
  355.      -------------              --------------
  356.      Printing-ASCII             PC1
  357.      Japanese-JISX0201-Roman    PC1
  358.      Japanese-JISX0201-Kana     PC1
  359.      Japanese-JISX0208          PC1 PC2
  360.      
  361.      
  362.      Escape sequence   ASCII equivalent   Meaning
  363.      ---------------   ----------------   -------
  364.      0x1B 0x28 0x4A    ESC ( J            invoke Japanese-JISX0201-Roman
  365.      0x1B 0x28 0x49    ESC ( I            invoke Japanese-JISX0201-Kana
  366.      0x1B 0x24 0x42    ESC $ B            invoke Japanese-JISX0208
  367.      0x1B 0x28 0x42    ESC ( B            invoke Printing-ASCII
  368.  
  369.    Initially, Printing-ASCII is invoked.
  370.  
  371. 
  372. File: internals.info,  Node: Internal Mule Encodings,  Next: CCL,  Prev: Encodings,  Up: MULE Character Sets and Encodings
  373.  
  374. Internal Mule Encodings
  375. =======================
  376.  
  377.    In XEmacs/Mule, each character set is assigned a unique number,
  378. called a "leading byte".  This is used in the encodings of a character.
  379. Leading bytes are in the range 0x80 - 0xFF (except for ASCII, which has
  380. a leading byte of 0), although some leading bytes are reserved.
  381.  
  382.    Charsets whose leading byte is in the range 0x80 - 0x9F are called
  383. "official" and are used for built-in charsets.  Other charsets are
  384. called "private" and have leading bytes in the range 0xA0 - 0xFF; these
  385. are user-defined charsets.
  386.  
  387.    More specifically:
  388.  
  389.      Character set           Leading byte
  390.      -------------           ------------
  391.      ASCII                   0
  392.      Composite               0x80
  393.      Dimension-1 Official    0x81 - 0x8D
  394.                                (0x8E is free)
  395.      Control-1               0x8F
  396.      Dimension-2 Official    0x90 - 0x99
  397.                                (0x9A - 0x9D are free;
  398.                                 0x9E and 0x9F are reserved)
  399.      Dimension-1 Private     0xA0 - 0xEF
  400.      Dimension-2 Private     0xF0 - 0xFF
  401.  
  402.    There are two internal encodings for characters in XEmacs/Mule.  One
  403. is called "string encoding" and is an 8-bit encoding that is used for
  404. representing characters in a buffer or string.  It uses 1 to 4 bytes per
  405. character.  The other is called "character encoding" and is a 19-bit
  406. encoding that is used for representing characters individually in a
  407. variable.
  408.  
  409.    (In the following descriptions, we'll ignore composite characters for
  410. the moment.  We also give a general (structural) overview first,
  411. followed later by the exact details.)
  412.  
  413. * Menu:
  414.  
  415. * Internal String Encoding::
  416. * Internal Character Encoding::
  417.  
  418. 
  419. File: internals.info,  Node: Internal String Encoding,  Next: Internal Character Encoding,  Up: Internal Mule Encodings
  420.  
  421. Internal String Encoding
  422. ------------------------
  423.  
  424.    ASCII characters are encoded using their position code directly.
  425. Other characters are encoded using their leading byte followed by their
  426. position code(s) with the high bit set.  Characters in private character
  427. sets have their leading byte prefixed with a "leading byte prefix",
  428. which is either 0x9E or 0x9F. (No character sets are ever assigned these
  429. leading bytes.) Specifically:
  430.  
  431.      Character set           Encoding (PC=position-code, LB=leading-byte)
  432.      -------------           --------
  433.      ASCII                   PC-1 |
  434.      Control-1               LB   |  PC1 + 0xA0 |
  435.      Dimension-1 official    LB   |  PC1 + 0x80 |
  436.      Dimension-1 private     0x9E |  LB         | PC1 + 0x80 |
  437.      Dimension-2 official    LB   |  PC1 + 0x80 | PC2 + 0x80 |
  438.      Dimension-2 private     0x9F |  LB         | PC1 + 0x80 | PC2 + 0x80
  439.  
  440.    The basic characteristic of this encoding is that the first byte of
  441. all characters is in the range 0x00 - 0x9F, and the second and
  442. following bytes of all characters is in the range 0xA0 - 0xFF.  This
  443. means that it is impossible to get out of sync, or more specifically:
  444.  
  445.   1. Given any byte position, the beginning of the character it is
  446.      within can be determined in constant time.
  447.  
  448.   2. Given any byte position at the beginning of a character, the
  449.      beginning of the next character can be determined in constant time.
  450.  
  451.   3. Given any byte position at the beginning of a character, the
  452.      beginning of the previous character can be determined in constant
  453.      time.
  454.  
  455.   4. Textual searches can simply treat encoded strings as if they were
  456.      encoded in a one-byte-per-character fashion rather than the actual
  457.      multi-byte encoding.
  458.  
  459.    None of the standard non-modal encodings meet all of these
  460. conditions.  For example, EUC satisfies only (2) and (3), while
  461. Shift-JIS and Big5 (not yet described) satisfy only (2). (All non-modal
  462. encodings must satisfy (2), in order to be unambiguous.)
  463.  
  464. 
  465. File: internals.info,  Node: Internal Character Encoding,  Prev: Internal String Encoding,  Up: Internal Mule Encodings
  466.  
  467. Internal Character Encoding
  468. ---------------------------
  469.  
  470.    One 19-bit word represents a single character.  The word is
  471. separated into three fields:
  472.  
  473.      Bit number:     18 17 16 15 14 13 12 11 10 09 08 07 06 05 04 03 02 01 00
  474.                      <------------> <------------------> <------------------>
  475.      Field:                1                  2                    3
  476.  
  477.    Note that fields 2 and 3 hold 7 bits each, while field 1 holds 5
  478. bits.
  479.  
  480.      Character set           Field 1         Field 2         Field 3
  481.      -------------           -------         -------         -------
  482.      ASCII                      0               0              PC1
  483.         range:                                                   (00 - 7F)
  484.      Control-1                  0               1              PC1
  485.         range:                                                   (00 - 1F)
  486.      Dimension-1 official       0            LB - 0x80         PC1
  487.         range:                                    (01 - 0D)      (20 - 7F)
  488.      Dimension-1 private        0            LB - 0x80         PC1
  489.         range:                                    (20 - 6F)      (20 - 7F)
  490.      Dimension-2 official    LB - 0x8F         PC1             PC2
  491.         range:                    (01 - 0A)       (20 - 7F)      (20 - 7F)
  492.      Dimension-2 private     LB - 0xE1         PC1             PC2
  493.         range:                    (0F - 1E)       (20 - 7F)      (20 - 7F)
  494.      Composite                 0x1F             ?               ?
  495.  
  496.    Note that character codes 0 - 255 are the same as the "binary
  497. encoding" described above.
  498.  
  499. 
  500. File: internals.info,  Node: CCL,  Prev: Internal Mule Encodings,  Up: MULE Character Sets and Encodings
  501.  
  502. CCL
  503. ===
  504.  
  505.      CCL PROGRAM SYNTAX:
  506.              CCL_PROGRAM := (CCL_MAIN_BLOCK
  507.                              [ CCL_EOF_BLOCK ])
  508.      
  509.              CCL_MAIN_BLOCK := CCL_BLOCK
  510.              CCL_EOF_BLOCK := CCL_BLOCK
  511.      
  512.              CCL_BLOCK := STATEMENT | (STATEMENT [STATEMENT ...])
  513.              STATEMENT :=
  514.                      SET | IF | BRANCH | LOOP | REPEAT | BREAK
  515.                      | READ | WRITE
  516.      
  517.              SET := (REG = EXPRESSION) | (REG SELF_OP EXPRESSION)
  518.                     | INT-OR-CHAR
  519.      
  520.              EXPRESSION := ARG | (EXPRESSION OP ARG)
  521.      
  522.              IF := (if EXPRESSION CCL_BLOCK CCL_BLOCK)
  523.              BRANCH := (branch EXPRESSION CCL_BLOCK [CCL_BLOCK ...])
  524.              LOOP := (loop STATEMENT [STATEMENT ...])
  525.              BREAK := (break)
  526.              REPEAT := (repeat)
  527.                      | (write-repeat [REG | INT-OR-CHAR | string])
  528.                      | (write-read-repeat REG [INT-OR-CHAR | string | ARRAY]?)
  529.              READ := (read REG) | (read REG REG)
  530.                      | (read-if REG ARITH_OP ARG CCL_BLOCK CCL_BLOCK)
  531.                      | (read-branch REG CCL_BLOCK [CCL_BLOCK ...])
  532.              WRITE := (write REG) | (write REG REG)
  533.                      | (write INT-OR-CHAR) | (write STRING) | STRING
  534.                      | (write REG ARRAY)
  535.              END := (end)
  536.      
  537.              REG := r0 | r1 | r2 | r3 | r4 | r5 | r6 | r7
  538.              ARG := REG | INT-OR-CHAR
  539.              OP :=   + | - | * | / | % | & | '|' | ^ | << | >> | <8 | >8 | //
  540.                      | < | > | == | <= | >= | !=
  541.              SELF_OP :=
  542.                      += | -= | *= | /= | %= | &= | '|=' | ^= | <<= | >>=
  543.              ARRAY := '[' INT-OR-CHAR ... ']'
  544.              INT-OR-CHAR := INT | CHAR
  545.      
  546.      MACHINE CODE:
  547.      
  548.      The machine code consists of a vector of 32-bit words.
  549.      The first such word specifies the start of the EOF section of the code;
  550.      this is the code executed to handle any stuff that needs to be done
  551.      (e.g. designating back to ASCII and left-to-right mode) after all
  552.      other encoded/decoded data has been written out.  This is not used for
  553.      charset CCL programs.
  554.      
  555.      REGISTER: 0..7  -- refered by RRR or rrr
  556.      
  557.      OPERATOR BIT FIELD (27-bit): XXXXXXXXXXXXXXX RRR TTTTT
  558.              TTTTT (5-bit): operator type
  559.              RRR (3-bit): register number
  560.              XXXXXXXXXXXXXXXX (15-bit):
  561.                      CCCCCCCCCCCCCCC: constant or address
  562.                      000000000000rrr: register number
  563.      
  564.      AAAA:   00000 +
  565.              00001 -
  566.              00010 *
  567.              00011 /
  568.              00100 %
  569.              00101 &
  570.              00110 |
  571.              00111 ~
  572.      
  573.              01000 <<
  574.              01001 >>
  575.              01010 <8
  576.              01011 >8
  577.              01100 //
  578.              01101 not used
  579.              01110 not used
  580.              01111 not used
  581.      
  582.              10000 <
  583.              10001 >
  584.              10010 ==
  585.              10011 <=
  586.              10100 >=
  587.              10101 !=
  588.      
  589.      OPERATORS:      TTTTT RRR XX..
  590.      
  591.      SetCS:          00000 RRR C...C         RRR = C...C
  592.      SetCL:          00001 RRR .....         RRR = c...c
  593.                      c.............c
  594.      SetR:           00010 RRR ..rrr         RRR = rrr
  595.      SetA:           00011 RRR ..rrr         RRR = array[rrr]
  596.                      C.............C         size of array = C...C
  597.                      c.............c         contents = c...c
  598.      
  599.      Jump:           00100 000 c...c         jump to c...c
  600.      JumpCond:       00101 RRR c...c         if (!RRR) jump to c...c
  601.      WriteJump:      00110 RRR c...c         Write1 RRR, jump to c...c
  602.      WriteReadJump:  00111 RRR c...c         Write1, Read1 RRR, jump to c...c
  603.      WriteCJump:     01000 000 c...c         Write1 C...C, jump to c...c
  604.                      C...C
  605.      WriteCReadJump: 01001 RRR c...c         Write1 C...C, Read1 RRR,
  606.                      C.............C         and jump to c...c
  607.      WriteSJump:     01010 000 c...c         WriteS, jump to c...c
  608.                      C.............C
  609.                      S.............S
  610.                      ...
  611.      WriteSReadJump: 01011 RRR c...c         WriteS, Read1 RRR, jump to c...c
  612.                      C.............C
  613.                      S.............S
  614.                      ...
  615.      WriteAReadJump: 01100 RRR c...c         WriteA, Read1 RRR, jump to c...c
  616.                      C.............C         size of array = C...C
  617.                      c.............c         contents = c...c
  618.                      ...
  619.      Branch:         01101 RRR C...C         if (RRR >= 0 && RRR < C..)
  620.                      c.............c         branch to (RRR+1)th address
  621.      Read1:          01110 RRR ...           read 1-byte to RRR
  622.      Read2:          01111 RRR ..rrr         read 2-byte to RRR and rrr
  623.      ReadBranch:     10000 RRR C...C         Read1 and Branch
  624.                      c.............c
  625.                      ...
  626.      Write1:         10001 RRR .....         write 1-byte RRR
  627.      Write2:         10010 RRR ..rrr         write 2-byte RRR and rrr
  628.      WriteC:         10011 000 .....         write 1-char C...CC
  629.                      C.............C
  630.      WriteS:         10100 000 .....         write C..-byte of string
  631.                      C.............C
  632.                      S.............S
  633.                      ...
  634.      WriteA:         10101 RRR .....         write array[RRR]
  635.                      C.............C         size of array = C...C
  636.                      c.............c         contents = c...c
  637.                      ...
  638.      End:            10110 000 .....         terminate the execution
  639.      
  640.      SetSelfCS:      10111 RRR C...C         RRR AAAAA= C...C
  641.                      ..........AAAAA
  642.      SetSelfCL:      11000 RRR .....         RRR AAAAA= c...c
  643.                      c.............c
  644.                      ..........AAAAA
  645.      SetSelfR:       11001 RRR ..Rrr         RRR AAAAA= rrr
  646.                      ..........AAAAA
  647.      SetExprCL:      11010 RRR ..Rrr         RRR = rrr AAAAA c...c
  648.                      c.............c
  649.                      ..........AAAAA
  650.      SetExprR:       11011 RRR ..rrr         RRR = rrr AAAAA Rrr
  651.                      ............Rrr
  652.                      ..........AAAAA
  653.      JumpCondC:      11100 RRR c...c         if !(RRR AAAAA C..) jump to c...c
  654.                      C.............C
  655.                      ..........AAAAA
  656.      JumpCondR:      11101 RRR c...c         if !(RRR AAAAA rrr) jump to c...c
  657.                      ............rrr
  658.                      ..........AAAAA
  659.      ReadJumpCondC:  11110 RRR c...c         Read1 and JumpCondC
  660.                      C.............C
  661.                      ..........AAAAA
  662.      ReadJumpCondR:  11111 RRR c...c         Read1 and JumpCondR
  663.                      ............rrr
  664.                      ..........AAAAA
  665.  
  666. 
  667. File: internals.info,  Node: The Lisp Reader and Compiler,  Next: Lstreams,  Prev: MULE Character Sets and Encodings,  Up: Top
  668.  
  669. The Lisp Reader and Compiler
  670. ****************************
  671.  
  672.    Not yet documented.
  673.  
  674. 
  675. File: internals.info,  Node: Lstreams,  Next: Consoles; Devices; Frames; Windows,  Prev: The Lisp Reader and Compiler,  Up: Top
  676.  
  677. Lstreams
  678. ********
  679.  
  680.    An "lstream" is an internal Lisp object that provides a generic
  681. buffering stream implementation.  Conceptually, you send data to the
  682. stream or read data from the stream, not caring what's on the other end
  683. of the stream.  The other end could be another stream, a file
  684. descriptor, a stdio stream, a fixed block of memory, a reallocating
  685. block of memory, etc.  The main purpose of the stream is to provide a
  686. standard interface and to do buffering.  Macros are defined to read or
  687. write characters, so the calling functions do not have to worry about
  688. blocking data together in order to achieve efficiency.
  689.  
  690. * Menu:
  691.  
  692. * Creating an Lstream::         Creating an lstream object.
  693. * Lstream Types::               Different sorts of things that are streamed.
  694. * Lstream Functions::           Functions for working with lstreams.
  695. * Lstream Methods::             Creating new lstream types.
  696.  
  697. 
  698. File: internals.info,  Node: Creating an Lstream,  Next: Lstream Types,  Up: Lstreams
  699.  
  700. Creating an Lstream
  701. ===================
  702.  
  703.    Lstreams come in different types, depending on what is being
  704. interfaced to.  Although the primitive for creating new lstreams is
  705. `Lstream_new()', generally you do not call this directly.  Instead, you
  706. call some type-specific creation function, which creates the lstream
  707. and initializes it as appropriate for the particular type.
  708.  
  709.    All lstream creation functions take a MODE argument, specifying what
  710. mode the lstream should be opened as.  This controls whether the
  711. lstream is for input and output, and optionally whether data should be
  712. blocked up in units of MULE characters.  Note that some types of
  713. lstreams can only be opened for input; others only for output; and
  714. others can be opened either way.  #### Richard Mlynarik thinks that
  715. there should be a strict separation between input and output streams,
  716. and he's probably right.
  717.  
  718.    MODE is a string, one of
  719.  
  720. `"r"'
  721.      Open for reading.
  722.  
  723. `"w"'
  724.      Open for writing.
  725.  
  726. `"rc"'
  727.      Open for reading, but "read" never returns partial MULE characters.
  728.  
  729. `"wc"'
  730.      Open for writing, but never writes partial MULE characters.
  731.  
  732. 
  733. File: internals.info,  Node: Lstream Types,  Next: Lstream Functions,  Prev: Creating an Lstream,  Up: Lstreams
  734.  
  735. Lstream Types
  736. =============
  737.  
  738. stdio
  739.  
  740. filedesc
  741.  
  742. lisp-string
  743.  
  744. fixed-buffer
  745.  
  746. resizing-buffer
  747.  
  748. dynarr
  749.  
  750. lisp-buffer
  751.  
  752. print
  753.  
  754. decoding
  755.  
  756. encoding
  757. 
  758. File: internals.info,  Node: Lstream Functions,  Next: Lstream Methods,  Prev: Lstream Types,  Up: Lstreams
  759.  
  760. Lstream Functions
  761. =================
  762.  
  763.  - Function: Lstream * Lstream_new (Lstream_implementation *IMP, CONST
  764.           char *MODE)
  765.      Allocate and return a new Lstream.  This function is not really
  766.      meant to be called directly; rather, each stream type should
  767.      provide its own stream creation function, which creates the stream
  768.      and does any other necessary creation stuff (e.g. opening a file).
  769.  
  770.  - Function: void Lstream_set_buffering (Lstream *LSTR,
  771.           Lstream_buffering BUFFERING, int BUFFERING_SIZE)
  772.      Change the buffering of a stream.  See `lstream.h'.  By default the
  773.      buffering is `STREAM_BLOCK_BUFFERED'.
  774.  
  775.  - Function: int Lstream_flush (Lstream *LSTR)
  776.      Flush out any pending unwritten data in the stream.  Clear any
  777.      buffered input data.  Returns 0 on success, -1 on error.
  778.  
  779.  - Macro: int Lstream_putc (Lstream *STREAM, int C)
  780.      Write out one byte to the stream.  This is a macro and so it is
  781.      very efficient.  The C argument is only evaluated once but the
  782.      STREAM argument is evaluated more than once.  Returns 0 on
  783.      success, -1 on error.
  784.  
  785.  - Macro: int Lstream_getc (Lstream *STREAM)
  786.      Read one byte from the stream.  This is a macro and so it is very
  787.      efficient.  The STREAM argument is evaluated more than once.
  788.      Return value is -1 for EOF or error.
  789.  
  790.  - Macro: void Lstream_ungetc (Lstream *STREAM, int C)
  791.      Push one byte back onto the input queue.  This will be the next
  792.      byte read from the stream.  Any number of bytes can be pushed back
  793.      and will be read in the reverse order they were pushed back - most
  794.      recent first. (This is necessary for consistency - if there are a
  795.      number of bytes that have been unread and I read and unread a
  796.      byte, it needs to be the first to be read again.) This is a macro
  797.      and so it is very efficient.  The C argument is only evaluated
  798.      once but the STREAM argument is evaluated more than once.
  799.  
  800.  - Function: int Lstream_fputc (Lstream *STREAM, int C)
  801.  - Function: int Lstream_fgetc (Lstream *STREAM)
  802.  - Function: void Lstream_fungetc (Lstream *STREAM, int C)
  803.      Function equivalents of the above macros.
  804.  
  805.  - Function: int Lstream_read (Lstream *STREAM, void *DATA, int SIZE)
  806.      Read SIZE bytes of DATA from the stream.  Return the number of
  807.      bytes read.  0 means EOF. -1 means an error occurred and no bytes
  808.      were read.
  809.  
  810.  - Function: int Lstream_write (Lstream *STREAM, void *DATA, int SIZE)
  811.      Write SIZE bytes of DATA to the stream.  Return the number of
  812.      bytes written.  -1 means an error occurred and no bytes were
  813.      written.
  814.  
  815.  - Function: void Lstream_unread (Lstream *STREAM, void *DATA, int SIZE)
  816.      Push back SIZE bytes of DATA onto the input queue.  The next call
  817.      to `Lstream_read()' with the same size will read the same bytes
  818.      back.  Note that this will be the case even if there is other
  819.      pending unread data.
  820.  
  821.  - Function: int Lstream_close (Lstream *STREAM)
  822.      Close the stream.  All data will be flushed out.
  823.  
  824.  - Function: void Lstream_reopen (Lstream *STREAM)
  825.      Reopen a closed stream.  This enables I/O on it again.  This is not
  826.      meant to be called except from a wrapper routine that reinitializes
  827.      variables and such - the close routine may well have freed some
  828.      necessary storage structures, for example.
  829.  
  830.  - Function: void Lstream_rewind (Lstream *STREAM)
  831.      Rewind the stream to the beginning.
  832.  
  833. 
  834. File: internals.info,  Node: Lstream Methods,  Prev: Lstream Functions,  Up: Lstreams
  835.  
  836. Lstream Methods
  837. ===============
  838.  
  839.  - Lstream Method: int reader (Lstream *STREAM, unsigned char *DATA,
  840.           int SIZE)
  841.      Read some data from the stream's end and store it into DATA, which
  842.      can hold SIZE bytes.  Return the number of bytes read.  A return
  843.      value of 0 means no bytes can be read at this time.  This may be
  844.      because of an EOF, or because there is a granularity greater than
  845.      one byte that the stream imposes on the returned data, and SIZE is
  846.      less than this granularity. (This will happen frequently for
  847.      streams that need to return whole characters, because
  848.      `Lstream_read()' calls the reader function repeatedly until it has
  849.      the number of bytes it wants or until 0 is returned.)  The lstream
  850.      functions do not treat a 0 return as EOF or do anything special;
  851.      however, the calling function will interpret any 0 it gets back as
  852.      EOF.  This will normally not happen unless the caller calls
  853.      `Lstream_read()' with a very small size.
  854.  
  855.      This function can be `NULL' if the stream is output-only.
  856.  
  857.  - Lstream Method: int writer (Lstream *STREAM, CONST unsigned char
  858.           *DATA, int SIZE)
  859.      Send some data to the stream's end.  Data to be sent is in DATA
  860.      and is SIZE bytes.  Return the number of bytes sent.  This
  861.      function can send and return fewer bytes than is passed in; in that
  862.      case, the function will just be called again until there is no
  863.      data left or 0 is returned.  A return value of 0 means that no
  864.      more data can be currently stored, but there is no error; the data
  865.      will be squirreled away until the writer can accept data. (This is
  866.      useful, e.g., if you're dealing with a non-blocking file
  867.      descriptor and are getting `EWOULDBLOCK' errors.)  This function
  868.      can be `NULL' if the stream is input-only.
  869.  
  870.  - Lstream Method: int rewinder (Lstream *STREAM)
  871.      Rewind the stream.  If this is `NULL', the stream is not seekable.
  872.  
  873.  - Lstream Method: int seekable_p (Lstream *STREAM)
  874.      Indicate whether this stream is seekable - i.e. it can be rewound.
  875.      This method is ignored if the stream does not have a rewind
  876.      method.  If this method is not present, the result is determined
  877.      by whether a rewind method is present.
  878.  
  879.  - Lstream Method: int flusher (Lstream *STREAM)
  880.      Perform any additional operations necessary to flush the data in
  881.      this stream.
  882.  
  883.  - Lstream Method: int pseudo_closer (Lstream *STREAM)
  884.  
  885.  - Lstream Method: int closer (Lstream *STREAM)
  886.      Perform any additional operations necessary to close this stream
  887.      down.  May be `NULL'.  This function is called when
  888.      `Lstream_close()' is called or when the stream is
  889.      garbage-collected.  When this function is called, all pending data
  890.      in the stream will already have been written out.
  891.  
  892.  - Lstream Method: Lisp_Object marker (Lisp_Object LSTREAM, void
  893.           (*MARKFUN) (Lisp_Object))
  894.      Mark this object for garbage collection.  Same semantics as a
  895.      standard `Lisp_Object' marker.  This function can be `NULL'.
  896.  
  897. 
  898. File: internals.info,  Node: Consoles; Devices; Frames; Windows,  Next: The Redisplay Mechanism,  Prev: Lstreams,  Up: Top
  899.  
  900. Consoles; Devices; Frames; Windows
  901. **********************************
  902.  
  903. * Menu:
  904.  
  905. * Introduction to Consoles; Devices; Frames; Windows::
  906. * Point::
  907. * Window Hierarchy::
  908. * The Window Object::
  909.  
  910. 
  911. File: internals.info,  Node: Introduction to Consoles; Devices; Frames; Windows,  Next: Point,  Up: Consoles; Devices; Frames; Windows
  912.  
  913. Introduction to Consoles; Devices; Frames; Windows
  914. ==================================================
  915.  
  916.    A window-system window that you see on the screen is called a
  917. "frame" in Emacs terminology.  Each frame is subdivided into one or
  918. more non-overlapping panes, called (confusingly) "windows".  Each
  919. window displays the text of a buffer in it. (See above on Buffers.) Note
  920. that buffers and windows are independent entities: Two or more windows
  921. can be displaying the same buffer (potentially in different locations),
  922. and a buffer can be displayed in no windows.
  923.  
  924.    A single display screen that contains one or more frames is called a
  925. "display".  Under most circumstances, there is only one display.
  926. However, more than one display can exist, for example if you have a
  927. "multi-headed" console, i.e. one with a single keyboard but multiple
  928. displays. (Typically in such a situation, the various displays act like
  929. one large display, in that the mouse is only in one of them at a time,
  930. and moving the mouse off of one moves it into another.) In some cases,
  931. the different displays will have different characteristics, e.g. one
  932. color and one mono.
  933.  
  934.    XEmacs can display frames on multiple displays.  It can even deal
  935. simultaneously with frames on multiple keyboards (called "consoles" in
  936. XEmacs terminology).  Here is one case where this might be useful: You
  937. are using XEmacs on your workstation at work, and leave it running.
  938. Then you go home and dial in on a TTY line, and you can use the
  939. already-running XEmacs process to display another frame on your local
  940. TTY.
  941.  
  942.    Thus, there is a hierarchy console -> display -> frame -> window.
  943. There is a separate Lisp object type for each of these four concepts.
  944. Furthermore, there is logically a "selected console", "selected
  945. display", "selected frame", and "selected window".  Each of these
  946. objects is distinguished in various ways, such as being the default
  947. object for various functions that act on objects of that type.  Note
  948. that every containing object rememembers the "selected" object among
  949. the objects that it contains: e.g. not only is there a selected window,
  950. but every frame remembers the last window in it that was selected, and
  951. changing the selected frame causes the remembered window within it to
  952. become the selected window.  Similar relationships apply for consoles
  953. to devices and devices to frames.
  954.  
  955. 
  956. File: internals.info,  Node: Point,  Next: Window Hierarchy,  Prev: Introduction to Consoles; Devices; Frames; Windows,  Up: Consoles; Devices; Frames; Windows
  957.  
  958. Point
  959. =====
  960.  
  961.    Recall that every buffer has a current insertion position, called
  962. "point".  Now, two or more windows may be displaying the same buffer,
  963. and the text cursor in the two windows (i.e. `point') can be in two
  964. different places.  You may ask, how can that be, since each buffer has
  965. only one value of `point'?  The answer is that each window also has a
  966. value of `point' that is squirreled away in it.  There is only one
  967. selected window, and the value of "point" in that buffer corresponds to
  968. that window.  When the selected window is changed from one window to
  969. another displaying the same buffer, the old value of `point' is stored
  970. into the old window's "point" and the value of `point' from the new
  971. window is retrieved and made the value of `point' in the buffer.  This
  972. means that `window-point' for the selected window is potentially
  973. inaccurate, and if you want to retrieve the correct value of `point'
  974. for a window, you must special-case on the selected window and retrieve
  975. the buffer's point instead.  This is related to why
  976. `save-window-excursion' does not save the selected window's value of
  977. `point'.
  978.  
  979. 
  980. File: internals.info,  Node: Window Hierarchy,  Next: The Window Object,  Prev: Point,  Up: Consoles; Devices; Frames; Windows
  981.  
  982. Window Hierarchy
  983. ================
  984.  
  985.    If a frame contains multiple windows (panes), they are always created
  986. by splitting an existing window along the horizontal or vertical axis.
  987. Terminology is a bit confusing here: to "split a window horizontally"
  988. means to create two side-by-side windows, i.e. to make a *vertical* cut
  989. in a window.  Likewise, to "split a window vertically" means to create
  990. two windows, one above the other, by making a *horizontal* cut.
  991.  
  992.    If you split a window and then split again along the same axis, you
  993. will end up with a number of panes all arranged along the same axis.
  994. The precise way in which the splits were made should not be important,
  995. and this is reflected internally.  Internally, all windows are arranged
  996. in a tree, consisting of two types of windows, "combination" windows
  997. (which have children, and are covered completely by those children) and
  998. "leaf" windows, which have no children and are visible.  Every
  999. combination window has two or more children, all arranged along the same
  1000. axis.  There are (logically) two subtypes of windows, depending on
  1001. whether their children are horizontally or vertically arrayed.  There is
  1002. always one root window, which is either a leaf window (if the frame
  1003. contains only one window) or a combination window (if the frame contains
  1004. more than one window).  In the latter case, the root window will have
  1005. two or more children, either horizontally or vertically arrayed, and
  1006. each of those children will be either a leaf window or another
  1007. combination window.
  1008.  
  1009.    Here are some rules:
  1010.  
  1011.   1. Horizontal combination windows can never have children that are
  1012.      horizontal combination windows; same for vertical.
  1013.  
  1014.   2. Only leaf windows can be split (obviously) and this splitting does
  1015.      one of two things: (a) turns the leaf window into a combination
  1016.      window and creates two new leaf children, or (b) turns the leaf
  1017.      window into one of the two new leaves and creates the other leaf.
  1018.      Rule (1) dictates which of these two outcomes happens.
  1019.  
  1020.   3. Every combination window must have at least two children.
  1021.  
  1022.   4. Leaf windows can never become combination windows.  They can be
  1023.      deleted, however.  If this results in a violation of (3), the
  1024.      parent combination window also gets deleted.
  1025.  
  1026.   5. All functions that accept windows must be prepared to accept
  1027.      combination windows, and do something sane (e.g. signal an error
  1028.      if so).  Combination windows *do* escape to the Lisp level.
  1029.  
  1030.   6. All windows have three fields governing their contents: these are
  1031.      "hchild" (a list of horizontally-arrayed children), "vchild" (a
  1032.      list of vertically-arrayed children), and "buffer" (the buffer
  1033.      contained in a leaf window).  Exactly one of these will be
  1034.      non-nil.  Remember that "horizontally-arrayed" means
  1035.      "side-by-side" and "vertically-arrayed" means "one above the
  1036.      other".
  1037.  
  1038.   7. Leaf windows also have markers in their `start' (the first buffer
  1039.      position displayed in the window) and `pointm' (the window's
  1040.      stashed value of `point' - see above) fields, while combination
  1041.      windows have nil in these fields.
  1042.  
  1043.   8. The list of children for a window is threaded through the `next'
  1044.      and `prev' fields of each child window.
  1045.  
  1046.   9. *Deleted windows can be undeleted*.  This happens as a result of
  1047.      restoring a window configuration, and is unlike frames, displays,
  1048.      and consoles, which, once deleted, can never be restored.
  1049.      Deleting a window does nothing except set a special `dead' bit to
  1050.      1 and clear out the `next', `prev', `hchild', and `vchild' fields,
  1051.      for GC purposes.
  1052.  
  1053.  10. Most frames actually have two top-level windows - one for the
  1054.      minibuffer and one (the "root") for everything else.  The modeline
  1055.      (if present) separates these two.  The `next' field of the root
  1056.      points to the minibuffer, and the `prev' field of the minibuffer
  1057.      points to the root.  The other `next' and `prev' fields are `nil',
  1058.      and the frame points to both of these windows.  Minibuffer-less
  1059.      frames have no minibuffer window, and the `next' and `prev' of the
  1060.      root window are `nil'.  Minibuffer-only frames have no root
  1061.      window, and the `next' of the minibuffer window is `nil' but the
  1062.      `prev' points to itself. (#### This is an artifact that should be
  1063.      fixed.)
  1064.  
  1065. 
  1066. File: internals.info,  Node: The Window Object,  Prev: Window Hierarchy,  Up: Consoles; Devices; Frames; Windows
  1067.  
  1068. The Window Object
  1069. =================
  1070.  
  1071.    Windows have the following accessible fields:
  1072.  
  1073. `frame'
  1074.      The frame that this window is on.
  1075.  
  1076. `mini_p'
  1077.      Non-`nil' if this window is a minibuffer window.
  1078.  
  1079. `buffer'
  1080.      The buffer that the window is displaying.  This may change often
  1081.      during the life of the window.
  1082.  
  1083. `dedicated'
  1084.      Non-`nil' if this window is dedicated to its buffer.
  1085.  
  1086. `pointm'
  1087.      This is the value of point in the current buffer when this window
  1088.      is selected; when it is not selected, it retains its previous
  1089.      value.
  1090.  
  1091. `start'
  1092.      The position in the buffer that is the first character to be
  1093.      displayed in the window.
  1094.  
  1095. `force_start'
  1096.      If this flag is non-`nil', it says that the window has been
  1097.      scrolled explicitly by the Lisp program.  This affects what the
  1098.      next redisplay does if point is off the screen: instead of
  1099.      scrolling the window to show the text around point, it moves point
  1100.      to a location that is on the screen.
  1101.  
  1102. `last_modified'
  1103.      The `modified' field of the window's buffer, as of the last time a
  1104.      redisplay completed in this window.
  1105.  
  1106. `last_point'
  1107.      The buffer's value of point, as of the last time a redisplay
  1108.      completed in this window.
  1109.  
  1110. `left'
  1111.      This is the left-hand edge of the window, measured in columns.
  1112.      (The leftmost column on the screen is column 0.)
  1113.  
  1114. `top'
  1115.      This is the top edge of the window, measured in lines.  (The top
  1116.      line on the screen is line 0.)
  1117.  
  1118. `height'
  1119.      The height of the window, measured in lines.
  1120.  
  1121. `width'
  1122.      The width of the window, measured in columns.
  1123.  
  1124. `next'
  1125.      This is the window that is the next in the chain of siblings.  It
  1126.      is `nil' in a window that is the rightmost or bottommost of a
  1127.      group of siblings.
  1128.  
  1129. `prev'
  1130.      This is the window that is the previous in the chain of siblings.
  1131.      It is `nil' in a window that is the leftmost or topmost of a group
  1132.      of siblings.
  1133.  
  1134. `parent'
  1135.      Internally, XEmacs arranges windows in a tree; each group of
  1136.      siblings has a parent window whose area includes all the siblings.
  1137.      This field points to a window's parent.
  1138.  
  1139.      Parent windows do not display buffers, and play little role in
  1140.      display except to shape their child windows.  Emacs Lisp programs
  1141.      usually have no access to the parent windows; they operate on the
  1142.      windows at the leaves of the tree, which actually display buffers.
  1143.  
  1144. `hscroll'
  1145.      This is the number of columns that the display in the window is
  1146.      scrolled horizontally to the left.  Normally, this is 0.
  1147.  
  1148. `use_time'
  1149.      This is the last time that the window was selected.  The function
  1150.      `get-lru-window' uses this field.
  1151.  
  1152. `display_table'
  1153.      The window's display table, or `nil' if none is specified for it.
  1154.  
  1155. `update_mode_line'
  1156.      Non-`nil' means this window's mode line needs to be updated.
  1157.  
  1158. `base_line_number'
  1159.      The line number of a certain position in the buffer, or `nil'.
  1160.      This is used for displaying the line number of point in the mode
  1161.      line.
  1162.  
  1163. `base_line_pos'
  1164.      The position in the buffer for which the line number is known, or
  1165.      `nil' meaning none is known.
  1166.  
  1167. `region_showing'
  1168.      If the region (or part of it) is highlighted in this window, this
  1169.      field holds the mark position that made one end of that region.
  1170.      Otherwise, this field is `nil'.
  1171.  
  1172. 
  1173. File: internals.info,  Node: The Redisplay Mechanism,  Next: Extents,  Prev: Consoles; Devices; Frames; Windows,  Up: Top
  1174.  
  1175. The Redisplay Mechanism
  1176. ***********************
  1177.  
  1178.    The redisplay mechanism is one of the most complicated sections of
  1179. XEmacs, especially from a conceptual standpoint.  This is doubly so
  1180. because, unlike for the basic aspects of the Lisp interpreter, the
  1181. computer science theories of how to efficiently handle redisplay are not
  1182. well-developed.
  1183.  
  1184.    When working with the redisplay mechanism, remember the Golden Rules
  1185. of Redisplay:
  1186.  
  1187.   1. It Is Better To Be Correct Than Fast.
  1188.  
  1189.   2. Thou Shalt Not Run Elisp From Within Redisplay.
  1190.  
  1191.   3. It Is Better To Be Fast Than Not To Be.
  1192.  
  1193. * Menu:
  1194.  
  1195. * Critical Redisplay Sections::
  1196. * Line Start Cache::
  1197.  
  1198. 
  1199. File: internals.info,  Node: Critical Redisplay Sections,  Next: Line Start Cache,  Up: The Redisplay Mechanism
  1200.  
  1201. Critical Redisplay Sections
  1202. ===========================
  1203.  
  1204.    Within this section, we are defenseless and assume that the
  1205. following cannot happen:
  1206.  
  1207.   1. garbage collection
  1208.  
  1209.   2. Lisp code evaluation
  1210.  
  1211.   3. frame size changes
  1212.  
  1213.    We ensure (3) by calling `hold_frame_size_changes()', which will
  1214. cause any pending frame size changes to get put on hold till after the
  1215. end of the critical section.  (1) follows automatically if (2) is met.
  1216. #### Unfortunately, there are some places where Lisp code can be called
  1217. within this section.  We need to remove them.
  1218.  
  1219.    If `Fsignal()' is called during this critical section, we will
  1220. `abort()'.
  1221.  
  1222.    If garbage collection is called during this critical section, we
  1223. simply return. #### We should abort instead.
  1224.  
  1225.    #### If a frame-size change does occur we should probably actually
  1226. be preempting redisplay.
  1227.  
  1228.